GitHub CLI project command が一般利用可能になりました

若槻龍太

2023.07.13

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、CX事業本部 Delivery部の若槻です。

GitHub projects は、Issue や Pull Request と統合的に利用できるプロジェクト管理機能です。

今までは projects を API で管理したい場合は GraphQL API を使用する必要がありましたが、このたびの GitHub CLI のアップデートにより projects command が一般利用可能（GA）となり、CLI から projects が管理ができるようになりました。

利用可能になったコマンド

今回利用可能になった projects command は以下となります。

gh project close
gh project copy
gh project create
gh project delete
gh project edit
gh project field-create
gh project field-delete
gh project field-list
gh project item-add
gh project item-archive
gh project item-create
gh project item-delete
gh project item-edit
gh project item-list
gh project list
gh project view

大きく分けて、projects 自体を管理するコマンド、projects 内のカードを管理するコマンド、およびカードのフィールドを管理するコマンドの3種類です。

コマンド一覧は下記から確認できます。

試してみる

権限の設定

まず、projects command を使用するためには GitHub の認証トークンに権限スコープ project が設定されている必要があります。

試しに project list コマンドを実行すると、read:project スコープが足りない旨のエラーが表示されます。

$ gh project list  
error: your authentication token is missing required scopes [read:project]
To request it, run:  gh auth refresh -s read:project

認証ステータスを確認すると、Token scopes に project が設定されていません。

$ gh auth status
github.com
  ✓ Logged in to github.com as cm-rwakatsuki (/Users/wakatsuki.ryuta/.config/gh/hosts.yml)
  ✓ Git operations for github.com configured to use https protocol.
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, read:org, repo, workflow

gh auth refresh コマンドで project スコープを追加します。

gh auth refresh -s project

再度認証ステータスを確認すると、Token scopes に project が設定されていることが確認できました。

$ gh auth status
github.com
  ✓ Logged in to github.com as cm-rwakatsuki (keyring)
  ✓ Git operations for github.com configured to use https protocol.
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, project, read:org, repo, workflow

project list コマンドも実行できるようになりました。

$ gh project list
NUMBER  TITLE                     STATE  ID
4       test project              open   PVT_kwHOA2ucV84AGIFl
3       DevIO Neta                open   PVT_kwHOA2ucV84AEG5E

アイテムの操作

projects command で最も行いたいであろうアイテムの操作を試してみます。

アイテムの追加

まず、gh project list コマンドで操作したい project の NUMBER を予め確認しておきます。

アイテムを project に追加する場合は、gh project item-add コマンドを使用します。先程 gh project list コマンドで確認した project の NUMBER により追加先の project を指定します。--owner では、追加先の project の owner 、--url では、追加するアイテムの URL を指定します。

gh project item-add 4 --owner "@me" --url https://github.com/cm-rwakatsuki/test/issues/5

注意点として、draft issue の追加はできないようです。

アイテム一覧の取得

アイテムの一覧は gh project item-list コマンドで取得できます。project の NUMBER および owner を指定します。

$ gh project item-list 4 --owner "@me"
TYPE        TITLE                 NUMBER  REPOSITORY          ID
Issue       デバッグ対応          2       cm-rwakatsuki/test  PVTI_lAHOA2ucV84AGIFlzgCiJl0
Issue       ボタンの配置を変更    3       cm-rwakatsuki/test  PVTI_lAHOA2ucV84AGIFlzgFjPTY
DraftIssue  ログ監視ツールの検討                              PVTI_lAHOA2ucV84AGIFlzgFjPUw
DraftIssue  ドキュメント修正                                  PVTI_lAHOA2ucV84AGIFlzgFjPVM
DraftIssue  APIの実装                                         PVTI_lAHOA2ucV84AGIFlzgGavco
Issue       API 実装              5       cm-rwakatsuki/test  PVTI_lAHOA2ucV84AGIFlzgH632s

ステータスは分からない点には注意です。project item-view コマンドがあっても良さそうなのですが、まだ実装されていませんでした。

フィールド一覧の取得

フィールドの一覧は gh project field-list コマンドで取得できます。project の NUMBER および owner を指定します。

$ gh project field-list 4 --owner "@me"
NAME                  DATA TYPE                   ID
Title                 ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dU
Assignees             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dY
Status                ProjectV2SingleSelectField  PVTSSF_lAHOA2ucV84AGIFlzgDh-dc
Labels                ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dg
Linked pull requests  ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dk
Reviewers             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-ds
Repository            ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dw
Milestone             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-d0
New Field             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgJ455o

これにより、例えばアイテムのステータスをコマンドで更新したい場合は ID PVTSSF_lAHOA2ucV84AGIFlzgDh-dc を指定すれば良いことが分かります。

アイテムの編集

アイテムの編集は gh project item-edit コマンドで行います。ワークフロー自動化のために最も使われるであろうコマンドだと思われますが、現状ではいくつか制限がありました。

draft issue の編集ができない

draft issue のタイトルを変更しようとすると、以下のようなエラーが表示されました。

$ gh project item-edit \
  --id "PVTI_lAHOA2ucV84AGIFlzgFjPUw" \
  --field-id "PVTSSF_lAHOA2ucV84AGIFlzgDh-dc" \
  --project-id "PVT_kwHOA2ucV84AGIFl" \
  --title "hoge"
ID must be the ID of the draft issue content which is prefixed with `DI_`

project list で確認した際は操作したい draft issue の ID は PVTI_ から始まる値だったのですが、DI_ で始まる ID を指定せよとのことです。よって draft issue を編集する方法が分かりませんでした。

ステータスの編集ができない

issue のステータスを変更しようとすると、以下のようなエラーが表示されました。

$ gh project item-edit \
  --id "PVTI_lAHOA2ucV84AGIFlzgFjPUw" \
  --field-id "PVTSSF_lAHOA2ucV84AGIFlzgDh-dc" \
  --project-id "PVT_kwHOA2ucV84AGIFl" \
  --single-select-option-id "Done"
GraphQL: The single select option Id does not belong to the field (updateProjectV2ItemFieldValue)

上記の single-select-option-id プロパティで指定したのは、ステータスの ID ではなく名前です。どうやら ID を指定する必要があるようですが、その ID の確認方法が分かりませんでした。